starflight3fandomcom-20200214-history
Trading and Commerce Module
This page is a discussion of the Trading and Commerce Module. The Trading and Commerce Module is designed specifically to handle all in-game transactions involving the player, affecting the player's cash on hand and the contents of the cargo_contents dictionary for each of the ships in their fleet. To say "Trading and Commerce" is a Humna Humna-eqsue redundancy; both refer to the same function in-game. The basic architecture of the module is similar to other modules within the game that handle basic data types (such as integers and strings) and hash tables / dictionaries. This module is required by the Starport Module and the Planetary Exploration Module specifically, though there may be some other applications available in other modules. The Trading and Commerce module is vitally important to the game, as trade is the player's primary source of in-game revenue. All code for the trade module object as well as the required child classes is located in the trade.py file. Summary Description An instance of the trade module is intended to be loaded during the game's initial setup. This will create the game's trader object and load the game's master item list into memory. The module's internal trade list generation routines are called during the initialization of the Starport Module and/or the Planetary Exploration Module (in the event that an inhabited world is indicated when that module initializes). This routine will include a call to the Onomastikon Module to select an appropriate name for the trader involved. The trade list generation routines will use the internal item list to generate a list of goods that traders on the planet will be interested in selling to the player, and goods they would like to buy from the player (taking into account what the player has in stock). If the game indicates that the player is entering a trade center, control of the game passes to the Trade Interface. Items sold to the traders are removed from the player's cargo list, and vice versa. If the player exits the trade center, control of the game passes back to whichever interface belongs to the method that called it; the Trade Interface can be re-engaged by the player by entering a new trade depot. Should the game's clock roll over one day while on a planet's surface, new trade good lists for that day will be generated. The lists are cleared out prior to the Starport or Planetary Exploration Modules passing control of the game to a different module. Data Structure of the Trader Object The following list is an indication of the various variables and methods that will be included in a Trader object. The following list is a rough indication of the various classes and variables that will be included. This is meant only as a guide; the names of the actual variables may be different from what's listed here (any changes to variable names should be updated here ASAP). Trader objects are meant to be used as direct objects, with no parent objects. Only one trader object is meant to be used in the game, and it is meant to be loaded by the core engine as the game is initially loading. Their data structure is as follows: *Class: Trade **Hash/Dictionary: Item_List **Hash/Dictionary: Trade_Messages **Hash/Dictionary: Trade_Data **Hash/Dictionary: Trade_Lists ***Class: Current_Trade ****String: szDateCreated ****Flag: bBarred (default to "False") ****Flag: bTechLocked (default to "True") ****String: Species ****String: Trader_Name ****String: Tech_Level ****String: Econ_Level ****String: Trade_Style ****List: Trader_Buys *****Class: Trade_Good ****List: Trader_Sells *****Class: Trade_Good ****Integer: Emotion_Index_Value ****Integer: Frustration_Level ****String: Frustration_Color ****String: Current_Item ****Integer: Player_Price ****Integer: Player_Last_Price ****Integer: Current_Offer ***Method: n_EnterCenter() ***Method: conductTrade(nItem, fBuy) ***Method: wheelAndDeal (nOffer) ***Method: _szHackAndSlash(szMsg) **Method: __init()__ **Method: makeLists(nXpos, nYpos, nFI) **Method: cleanOut() Data Structure of the Trade Good Object The following list is an indication of the various variables and methods that will be included in a Trade Good object. The following list is a rough indication of the various classes and variables that will be included. This is meant only as a guide; the names of the actual variables may be different from what's listed here (any changes to variable names should be updated here ASAP). Trade Good objects are meant to be used as direct objects, with no parent objects. Trade Good objects are meant to be created any time an item needs to be added to the player's inventory (usually when an item is bought or picked up on a planet's ssurface), and are meant to be created on the fly as the game progresses. Their data structure is as follows: *Class: Trade_Good **String: Name **String: Category (default to "Curio") **String: Tech_Level (default to "Stone Age") **String: Type (default to "None") **String: Description (default to "N/A") **Float: Unit_Volume **Integer: Current_Price **Integer: Best_Price_Point **Integer: Standard_Trade_Value **Integer: Initial_Price **Integer: Boundary_price **Enum: Trade_Status (NOT_BARTERED, BARTERED_ONCE, BARTERED_TWICE, BARTERED_THRICE, BARTERED_FOUR_TIMES, DONE_BARTERING; default to NOT_BARTERED) **Integer: nMaxAmount (default to 10000) Interface The trade interface consists of four separate areas, as demonstrated in the graphic: * Message Box * Image Box * Info Box * Interface Buttons The largest of the six interface areas is the Message Box, which is located in the large area on the right-hand side of the screen. This is where the game displays all text information being sent to the player, including greetings, trade-related messages, and trade good lists. Text sent to the Message Box remains visible to the player unless an action occurs that clears out the box (such as concluding a transaction), or until enough text has been sent to the Message Box to require it to "scroll down". If a message sent to the Message Box is long enough that it would scroll down before the player has had an opportunity to read all of it, the message can be set to "pause" mid-way through its display (this should never happen, but which we can account for anyway since a similar will be needed for the Starship Interface's Message Box). The Image Box is located in the upper-left-hand side of the screen. This area is used solely for the display of images, and can either display a static image of the trader or an image of the trade good in any ongoing transaction. The image shifts to the trade good in question once trade begins on that good, and switches back to an image of the trader once the transaction is complete. To fill this area and display properly, all images related to trade should be standardized to the same overall size, and preferably to the same file format (as of this writing, the desired file format is .PNG, with a resolution of 260x190 at 300 dpi.) Located immediately below the Image Box is the Info Box. This is an auxiliary text area that contains such information as the name of the good being bought or sold, the type of transaction that is taking place (either buying or selling; this is from the player's point of view), the STV percentage of a selected good (note that this can be displayed prior to actually initiating trade on an item, to give the player a better sense of what kind of deal they ultimately get out of a given transaction), the trader's current offer for that good, and the player's current amount of available funds. An extension of this area exists in the bar across the top of the screen, where the name of the race is displayed, followed by the name of the individual trader (as generated by the Onomastikon module). Finally, the Interface Buttons are located at the bottom of the screen. There are three large buttons in this area, labeled "Buy", "Sell" and "Exit". They may be activated one at a time in one of three ways: by clicking on them with the mouse, by using an appropriate hotkey for the desired menu (default hotkeys are F1 to F3 inclusive on the keyboard, with F1 corresponding to Buy and each successive key to the right corresponding to the next button to the right), or by using the arrow keys followed by the Module Status This is current as of December 22, 2010. This module is currently in the completed design phases; specific descriptions of the intended functions of modules have been written at this point, but no actual code has been written related to the module as yet (with the possible exception of XML files). The items.xml file has been redesigned twice, and should be close to a final permutation at this point, though I'll need to test the module before I know for sure. The trade_data.xml file is still incomplete, though its basic design is pretty well set. Likewise, the trade_messages.xml file is complete enough to be usable, but there have been no new messages added specifically for SF3. Artwork will need to be designed for this module, but until the game's standards are set in stone (as far as an engine to base it off of, anyway), it'll be difficult to ascertain exactly what is needed. CURRENT NOTES: During the brief development of the Starport Bank Office Sub-Module, a list was added to the Player object to keep track of transactions (this list is the same one that is accessed by the aforementioned Bank Module when it is activated). It was realized that in order for that list to do any good, any module that conducts financial transactions will need to add an entry to this list whenever a transaction is concluded. Such a function has not yet been written into this module; that will need to be done at some point in the future. This module will maintain completed design status until work on the necessary method's description begins. ---- NEXT: Encounter Module PREVIOUS: Planetary Exploration Module TOP ----